[TypeScript] HubSpot APIを使用してリストにコンタクトを追加する

[TypeScript] HubSpot APIを使用してリストにコンタクトを追加する

Clock Icon2024.09.16

どうも!オペ部の西村祐二です!

HubSpotのAPIを使ってコンタクトをリストに追加する処理を実装する機会がありました。備忘録を兼ねてブログにしておきます。

リストとは

特定の条件に基づいてコンタクト(顧客、リードなど)をグループ化するための機能です。リストを使うことで、マーケティングやセールスの活動を効率化し、ターゲットとなるオーディエンスに対してパーソナライズされたコミュニケーションを行うことができます。例えば、キャンペーンに関するメール通知を許可したコンタクトをリストに追加しておけば、効率よくメールマーケティングキャンペーンを行うことができます。

やってみる

今回、HubSpot APIを利用するためにNode.jsのライブラリを使用します。

https://github.com/HubSpot/hubspot-api-nodejs

環境

  • Node.js: v20.11.1
  • hubspot-api-nodejs: 11.2.0
  • 対象のリスト:静的リスト

アクセストークンの発行

非公開アプリを作成しアクセストークンと取得します。

007e140b91e62ca1ca6386ffb9d0c6950cd0e6146150646419640048cf893afe

権限としてlistに関するスコープを付与しておきます。

  • crm.lists.write
  • crm.lists.read

認証タブからアクセストークンを取得できます。

44d101572b0efe210da28d346294957accbfdf4e6350cb4c1ab05a5d1ece1940

リストのILSリストIDを取得する

追加したいリストのILSリストIDを取得しておきます。

e9bde1f5d79982d7589fa8eb3d63f38b6e0bf6f4c966798076ef5317cf3268c2

ILSリストIDはリストの「詳細」から確認することができます。

07d37ba2eee96149e44c654bdea414682d343adc7bb9216d730c665ad96d4599

ちなみにリストIDとILSリストIDの違いは以下とのことです。

リストIDは、サードパーティーの連携でリストを参照するとき、またはv1 Lists APIを使用するときに使用されます。ILS リスト ID は、Exports APIまたはv3 Lists APIを使用する際に参照されます。どちらのIDも、リストに移動して詳細をクリックすることで見つけることができる。

https://knowledge.hubspot.com/ja/lists/lists-faq

サンプル実装

各種ライブラリをインストール

npm install @hubspot/api-client

Typescriptをインストール

npm install typescript --save-dev 

初期化

npx tsc --init --rootDir src --outDir lib --esModuleInterop --resolveJsonModule --lib es6,dom --module commonjs

アクセストークンや環境などが正常か動作確認のために、コンタクトを検索する処理で確認します。

test.ts
import { Client } from "@hubspot/api-client";
import {
  FilterOperatorEnum,
  PublicObjectSearchRequest,
} from "@hubspot/api-client/lib/codegen/crm/companies";
const hubspotClient = new Client({
  accessToken: "your token",
});

(async () => {
  const objectSearchRequest: PublicObjectSearchRequest = {
    filterGroups: [
      {
        filters: [
          {
            propertyName: "createdate",
            operator: FilterOperatorEnum.Gte,
            value: "1715709177000",
          },
        ],
      },
    ],
    sorts: ["-createdate"],
    properties: ["email", "createdate"],
    limit: 100,
    after: "0",
  };

  const response = await hubspotClient.crm.contacts.searchApi.doSearch(
    objectSearchRequest
  );

  console.log(JSON.stringify(response, null, 2));
})();

実行

npx tsx ./test.ts

出力

うまくいけば下記のように検索結果が表示されます。

{
  "total": 16,
  "results": [
    {
      "createdAt": "2024-09-01T13:45:45.993Z",
      "archived": false,
      "id": "53915110775",
      "properties": {
        "createdate": "2024-09-01T13:45:45.993Z",
        "email": "xxxxx@xxxxxxx",
        "hs_object_id": "1234567890",
        "lastmodifieddate": "2024-09-01T15:31:32.686Z"
      },
      "updatedAt": "2024-09-01T15:31:32.686Z"
    },
    ...
  ]
}

環境構築ができたら次は本題のコンタクをリストを追加する処理

test.ts
import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({
  accessToken: "your token",
});

(async () => {
  const listId = 000;
  const contactIds = [1234567890];

  const response = await hubspotClient.crm.lists.membershipsApi.add(
    listId,
    contactIds
  );

  console.log(JSON.stringify(response, null, 2));
})();

実行

npx tsx ./test.ts

出力

{}

エラーなく実行完了したら、リストにコンタクトが追加されたか画面から確認しておきましょう

2e3549628d12a8589da427d74daa35bc4d9f380eab063423c48c75c9c55790e6

さいごに

HubSpot APIを使用してリストにコンタクトを追加する方法を紹介しました。

調べても、公式サイトぐらいしかヒットしなかったのでブログにしてみました。

誰かの参考になれば幸いです。

参考

https://developers.hubspot.com/beta-docs/reference/api/crm/lists/#put-%2Fcrm%2Fv3%2Flists%2F{listid}%2Fmemberships%2Fadd

https://developers.hubspot.com/docs/api/crm/lists

https://legacydocs.hubspot.com/docs/methods/lists/add_contact_to_list

Share this article

facebook logohatena logotwitter logo

© Classmethod, Inc. All rights reserved.